Add introduction section#158
Conversation
relaxing as JSON-LD is not only media type Co-authored-by: Ted Thibodeau Jr <tthibodeau@openlinksw.com>
elaborate on private, public and restricted Co-authored-by: Ted Thibodeau Jr <tthibodeau@openlinksw.com>
Co-authored-by: Ted Thibodeau Jr <tthibodeau@openlinksw.com>
point that an LWS account not required; plus CIDs Co-authored-by: Ted Thibodeau Jr <tthibodeau@openlinksw.com>
Co-authored-by: Ted Thibodeau Jr <tthibodeau@openlinksw.com>
| </p> | ||
| <p>This specification is intended to be used by:</p> | ||
| <ul> | ||
| <li>Developers building client applications that access a user’s LWS resources</li> |
There was a problem hiding this comment.
| <li>Developers building client applications that access a user’s LWS resources</li> | |
| <li>Developers building client applications that access a user's external web resources</li> |
An LWS Resource isn't defined yet
There was a problem hiding this comment.
Yes, but it comes after. I suggest we keep your text the same and hyperlink it to the definition.
There was a problem hiding this comment.
| <li>Developers building client applications that access a user’s LWS resources</li> | |
| <li>Developers building client applications that access a user’s <a>LWS resource</a>s</li> |
Co-authored-by: Ted Thibodeau Jr <tthibodeau@openlinksw.com>
| <li>Server implementers building compliant LWS servers that mediate access to a user’s external web resources</li> | ||
| </ul> | ||
| <p> | ||
| Different compliant servers each maintain their own hierarchy of linked resources. A user can navigate across servers using the same identity, with access to each server’s resources determined by the permissions granted by that server’s resource managers. |
There was a problem hiding this comment.
I'm curious why the ampersand-escaped curly apostrophes (’ ’) are preferred over the straight (' '), where the latter are easily typed and read as a single character in the HTML source as well as the delivered rendering, while the former require careful typing and reading of 7 characters wedged between two other non-space characters, as well as the non-space characters surrounding those 7, all of which means that spell-check is even less helpful than usual, when checking HTML files.
…/lws-protocol into introduction-section
| This specification defines the Linked Web Storage (LWS) Protocol, which enables client applications to access and manage web resources stored externally, based on the identity and permissions of the user. | ||
| </p> | ||
| <p> | ||
| By standardising how a LWS server manages and provides access to a hierarchy of linked resources, the protocol enables users to use different LWS client applications to interact with the same stored data. These linked resources are defined through containers and containment relationships that describe where things are located, and metadata that describes how the resources relate to each other. |
There was a problem hiding this comment.
| By standardising how a LWS server manages and provides access to a hierarchy of linked resources, the protocol enables users to use different LWS client applications to interact with the same stored data. These linked resources are defined through containers and containment relationships that describe where things are located, and metadata that describes how the resources relate to each other. | |
| By standardising how an LWS server manages and provides access to a hierarchy of linked resources, the protocol enables users to use different LWS client applications to interact with the same stored data. These linked resources are defined through containers and containment relationships that describe where things are located, and metadata that describes how the resources relate to each other. |
| This specification defines the Linked Web Storage (LWS) Protocol, which enables client applications to access and manage web resources stored externally, based on the identity and permissions of the user. | ||
| </p> | ||
| <p> | ||
| By standardising how a LWS server manages and provides access to a hierarchy of linked resources, the protocol enables users to use different LWS client applications to interact with the same stored data. These linked resources are defined through containers and containment relationships that describe where things are located, and metadata that describes how the resources relate to each other. |
There was a problem hiding this comment.
Are we sure "containers and containment relationships" and "metadata" are of equal (and most important) weight regarding what is meant by "linked resources"? I thought container is a specification detail, and what matters more is the metadata and returned JSON-LD/RDF document about resource locations / relationships.
| This specification defines the Linked Web Storage (LWS) Protocol, which enables client applications to access and manage web resources stored externally, based on the identity and permissions of the user. | ||
| </p> | ||
| <p> | ||
| By standardising how a LWS server manages and provides access to a hierarchy of linked resources, the protocol enables users to use different LWS client applications to interact with the same stored data. These linked resources are defined through containers and containment relationships that describe where things are located, and metadata that describes how the resources relate to each other. |
There was a problem hiding this comment.
The part "metadata that describes how the resources relate to each other" doesn't appear right to me... Metadata are more than that, even just considering the most critical parts of LWS (e.g. access / permission, types, etc).
| By standardising how a LWS server manages and provides access to a hierarchy of linked resources, the protocol enables users to use different LWS client applications to interact with the same stored data. These linked resources are defined through containers and containment relationships that describe where things are located, and metadata that describes how the resources relate to each other. | ||
| </p> | ||
| <p> | ||
| The protocol defines standard operations on these resources to create, read, update, and delete. Resources, their containment, and their metadata are managed by the server, commonly as a set of JSON-LD documents. Each resource is identified by a URI. A client navigates the resource hierarchy from a root container, discovering contained resources and their relations through links provided in server responses. |
There was a problem hiding this comment.
| The protocol defines standard operations on these resources to create, read, update, and delete. Resources, their containment, and their metadata are managed by the server, commonly as a set of JSON-LD documents. Each resource is identified by a URI. A client navigates the resource hierarchy from a root container, discovering contained resources and their relations through links provided in server responses. | |
| The protocol defines standard operations on these resources to create, read, update, and delete. Resources, their containment, and their metadata are partially managed by the server, commonly as a set of JSON-LD documents. Each resource is identified by a URI. A client navigates the resource hierarchy from a root container, discovering contained resources and their relations through links provided in server responses. |
There was a problem hiding this comment.
@renyuneyun
Since "Resources" are included in the list, I don't think that "managed" here means "has exclusive control over", and so "partially" may not be required here...
@jeremycaine
I would remove "commonly as a set of JSON-LD documents." which overemphasizes the role of JSON-LD in LWS. Granted, all LWS-specific resources (containers, in particular) have JSON-LD representations. But primary resources and metadata can use a variert of other formats.
| The protocol defines standard operations on these resources to create, read, update, and delete. Resources, their containment, and their metadata are managed by the server, commonly as a set of JSON-LD documents. Each resource is identified by a URI. A client navigates the resource hierarchy from a root container, discovering contained resources and their relations through links provided in server responses. | ||
| </p> | ||
| <p> | ||
| A user’s identity is confirmed through an identity provider external to the Linked Web Storage server. This separation means the server does not manage credentials directly; rather, it receives and validates a signed authentication credential as a token issued by a trusted identity provider. A user can therefore present their existing identity to any compliant server, without needing a new or existing separate account on that server. User authentication is defined in companion specifications for OpenID Connect, SAML 2.0, and self-signed controlled identifiers (CIDs). |
There was a problem hiding this comment.
| A user’s identity is confirmed through an identity provider external to the Linked Web Storage server. This separation means the server does not manage credentials directly; rather, it receives and validates a signed authentication credential as a token issued by a trusted identity provider. A user can therefore present their existing identity to any compliant server, without needing a new or existing separate account on that server. User authentication is defined in companion specifications for OpenID Connect, SAML 2.0, and self-signed controlled identifiers (CIDs). | |
| A user’s identity is confirmed through an identity provider that can be external to the Linked Web Storage server. This separation means the server does not manage credentials directly; rather, it receives and validates a signed authentication credential as a token issued by a trusted identity provider. A user can therefore present their existing identity to any compliant server, without needing a new or existing separate account on that server. User authentication is defined in companion specifications for OpenID Connect, SAML 2.0, and self-signed controlled identifiers (CIDs). |
There was a problem hiding this comment.
I understood from the April f2f that we said an LWS server does not implement the identity server - out of scope, an external system. If that is not correct then we can apply your suggestion. Do others recall?
There was a problem hiding this comment.
From the f2f meeting, an LWS server is not required to implement an identity server. That is different than saying that an LWS server must not implement an identity server. The suggested change clarifies that an identity provider can be external to the LWS server (but is not required to be)
| By standardising how a LWS server manages and provides access to a hierarchy of linked resources, the protocol enables users to use different LWS client applications to interact with the same stored data. These linked resources are defined through containers and containment relationships that describe where things are located, and metadata that describes how the resources relate to each other. | ||
| </p> | ||
| <p> | ||
| The protocol defines standard operations on these resources to create, read, update, and delete. Resources, their containment, and their metadata are managed by the server, commonly as a set of JSON-LD documents. Each resource is identified by a URI. A client navigates the resource hierarchy from a root container, discovering contained resources and their relations through links provided in server responses. |
There was a problem hiding this comment.
@renyuneyun
Since "Resources" are included in the list, I don't think that "managed" here means "has exclusive control over", and so "partially" may not be required here...
@jeremycaine
I would remove "commonly as a set of JSON-LD documents." which overemphasizes the role of JSON-LD in LWS. Granted, all LWS-specific resources (containers, in particular) have JSON-LD representations. But primary resources and metadata can use a variert of other formats.
| <p>This specification is intended to be used by:</p> | ||
| <ul> | ||
| <li>Developers building client applications that access a user’s LWS resources</li> | ||
| <li>Server implementers building compliant LWS servers that mediate access to a user’s external web resources</li> |
There was a problem hiding this comment.
| <li>Server implementers building compliant LWS servers that mediate access to a user’s external web resources</li> | |
| <li>Server implementers building compliant LWS servers that mediate access to a user’s web resources</li> |
I don't understand why those resources are qualified as "external". External to what? I read it as "external to the server", which is not the idea I have of your typical LWS resource. (yes, an LWS server, just like an HTTP server, could be a front-end for a legacy system which is the actual "location" of the resources, but many LWS servers will actually "own" their resources -- plus, from the client's perspective, this distinction does not really matters).
There was a problem hiding this comment.
I have removed references to 'externally managed'. I now see it that an LWS server define 1 or more storages. Those storages are at any URL location. Then the LWS manages a hierarchy of containers/data resource in those storages. The LWS server does CRUD on the data resources. Some other non-LWS external actor has the power to delete a resource by example - resulting in the LWS hierarchy information being out of sync (and so return 'resource not found' error.
| By standardising how an LWS server manages and provides access to a hierarchy of linked resources, the protocol enables users to use different LWS client applications to interact with the same stored data. These linked resources are defined through containers and containment relationships that describe where things are located, and metadata that describes how the resources relate to each other. | ||
| </p> | ||
| <p> | ||
| The protocol defines standard operations on these resources to create, read, update, and delete. Resources, their containment, and their metadata are managed by the server as a set of JSON-LD documents (and other representations). Each resource is identified by a URI. A client navigates the resource hierarchy from a root container, discovering contained resources and their relations through links provided in server responses. |
There was a problem hiding this comment.
"A client navigates the resource hierarchy from a root container"
-->
"A client navigates the resource hierarchy from a root container which is the Storage resource itself,"
There was a problem hiding this comment.
I don't see why introduction should address such a nuance. There are already discussions in
No matter of the outcome I would still prefer that introduction stays generic enough that it doesn't affect it.
There was a problem hiding this comment.
agree with @elf-pavlik, we should keep the introduction high-level.
| A user's identity is confirmed through an identity provider that can be external to the Linked Web Storage server. This separation means the server does not manage credentials directly; rather, it receives and validates a signed authentication credential as a token issued by a trusted identity provider. A user can therefore present their existing identity to any compliant server, without needing a new or existing separate account on that server. User authentication is defined in companion specifications for OpenID Connect, SAML 2.0, and self-signed controlled identifiers (CIDs). | ||
| </p> | ||
| <p> | ||
| Authorization determines whether a requesting user has permission to access a resource or perform an operation on it. A compliant LWS server designates a resource manager for each resource that determines whether a resource is private (i.e., available only to its owner), restricted (i.e., available to a defined set of users), or public (i.e., available to any user). The server enforces the access decisions of the resource manager when handling each client request. |
There was a problem hiding this comment.
"resource manager" I see now from the diagrams that this is referring to the top level system interface component of the Storage, so why not call this the "Storage Manager"?
There was a problem hiding this comment.
let's discuss - Resource Manager description is "Manages data resources, containers, containment and linksets" - this could expand to add in all things in LWS server including authorisation and authentication objects; we have Storage Controller controlling all the resources in the storage.
Storage Controller is in Terminology; Resource Manager or Storage Manager are not yet in the Terminnology section.
|
update of various
I believe only outstanding debate point was a name for what is currently "Resource Manager". I see this as the component that manages any operational object of the LWS server through other components including authentication, authorisation, storage, and data resources. |
| This specification defines the Linked Web Storage (LWS) Protocol, which enables client applications to access and manage web resources, based on the identity and permissions of an agent. | ||
| </p> | ||
| <p> | ||
| By standardising how an LWS server manages and provides access to a hierarchy of linked resources, the protocol enables users to use different LWS client applications to interact with the same stored data. These linked resources are defined through containers and containment relationships that describe where things are located, and metadata that describes how the resources relate to each other. |
There was a problem hiding this comment.
The W3C style guide recommends using US English spelling.
| By standardising how an LWS server manages and provides access to a hierarchy of linked resources, the protocol enables users to use different LWS client applications to interact with the same stored data. These linked resources are defined through containers and containment relationships that describe where things are located, and metadata that describes how the resources relate to each other. | |
| By standardizing how an LWS server manages and provides access to a hierarchy of linked resources, the protocol enables users to use different LWS client applications to interact with the same stored data. These linked resources are defined through containers and containment relationships that describe where things are located, and metadata that describes how the resources relate to each other. |
| By standardising how an LWS server manages and provides access to a hierarchy of linked resources, the protocol enables users to use different LWS client applications to interact with the same stored data. These linked resources are defined through containers and containment relationships that describe where things are located, and metadata that describes how the resources relate to each other. | ||
| </p> | ||
| <p> | ||
| The protocol defines standard operations on these resources to create, read, update, and delete. Resources, their containment, and their metadata are managed by the server as a set of JSON-LD documents (and other representations). Each resource is identified by a URI. A client navigates the resource hierarchy from a root container, discovering contained resources and their relations through links provided in server responses. |
There was a problem hiding this comment.
agree with @elf-pavlik, we should keep the introduction high-level.
| The protocol defines standard operations on these resources to create, read, update, and delete. Resources, their containment, and their metadata are managed by the server as a set of JSON-LD documents (and other representations). Each resource is identified by a URI. A client navigates the resource hierarchy from a root container, discovering contained resources and their relations through links provided in server responses. | ||
| </p> | ||
| <p> | ||
| A agent's identity is confirmed through an identity provider that can be external to the Linked Web Storage server. This separation means the server does not manage credentials directly; rather, it receives and validates a signed authentication credential as a token issued by a trusted identity provider. A user can therefore present their existing identity to any compliant server, without needing a new or existing separate account on that server. User authentication is defined in companion specifications for OpenID Connect, SAML 2.0, and self-signed controlled identifiers (CIDs). |
There was a problem hiding this comment.
This paragraph gets into a lot of nuance about user identity that may or may not be true at "any compliant server". It might be better to focus more on how agents identify themselves with globally unique identifiers. Also, be careful about statements such as "User authentication is defined in ..." -- we don't define user authentication anywhere, but we do define how to integrate with some widely supported authentication systems.
| A agent's identity is confirmed through an identity provider that can be external to the Linked Web Storage server. This separation means the server does not manage credentials directly; rather, it receives and validates a signed authentication credential as a token issued by a trusted identity provider. A user can therefore present their existing identity to any compliant server, without needing a new or existing separate account on that server. User authentication is defined in companion specifications for OpenID Connect, SAML 2.0, and self-signed controlled identifiers (CIDs). | ||
| </p> | ||
| <p> | ||
| Authorization determines whether a requesting agent has permission to access a resource or perform an operation on it. A compliant LWS server designates a resource manager for each resource that determines whether a resource is private (i.e., available only to its owner), restricted (i.e., available to a defined set of users), or public (i.e., available to any user). The server enforces the access decisions of the resource manager when handling each client request. |
There was a problem hiding this comment.
We will also want to be careful about how much detail goes into this. "Private", "Restricted" and "Public" are somewhat simplistic measures of how authorization rules are expressed. There may also be operator or federation-defined rules that come into play, depending on specific deployment considerations. For example, there may be resources available to all users but only if they use certain applications. Or resources that are only available to certain attested AI agents (no users are involved)
| </p> | ||
| <p>This specification is intended to be used by:</p> | ||
| <ul> | ||
| <li>Developers building client applications that access an agent's LWS resources</li> |
There was a problem hiding this comment.
| <li>Developers building client applications that access an agent's LWS resources</li> | |
| <li>Developers building client applications that access LWS resources</li> |
| <p>This specification is intended to be used by:</p> | ||
| <ul> | ||
| <li>Developers building client applications that access an agent's LWS resources</li> | ||
| <li>Server implementers building compliant LWS servers that mediate access to an agent's web resources</li> |
There was a problem hiding this comment.
| <li>Server implementers building compliant LWS servers that mediate access to an agent's web resources</li> | |
| <li>Developers building compliant servers that mediate access to LWS resources</li> |
| <li>Server implementers building compliant LWS servers that mediate access to an agent's web resources</li> | ||
| </ul> | ||
| <p> | ||
| Different compliant servers each maintain their own hierarchy of linked resources. An agent can navigate across servers using the same identity, with access to each server's resources determined by the permissions granted by that servers resource managers. |
There was a problem hiding this comment.
This may be true in some cases, but it is not the case that an arbitrary agent identity can be used with every server.
9 participants
Editorial - write an introduction section to the LWS specification
Preview | Diff